*************************************************************** VISCNTL.TXT Copyright (c) 1997 Visio Corporation. All rights reserved. *************************************************************** To view this file in Notepad, choose Word Wrap from the Edit menu. To print it neatly from Notepad, adjust the width of the Notepad window such that the window is about the same width as the first line of asterisks. This file provides information about using Visio as an ActiveX control in a custom Visio solution. It assumes that you have a basic understanding of COM and ActiveX. It also assumes that you are familiar with Automation in Visio and have a working knowledge of C++ or Microsoft Visual Basic. For information about creating Visio solutions that use Automation, see the Developing Visio Solutions manual. It contains details about the Visio object model and about using Visual Basic or C++ to control Visio. For the latest information about developing Visio solutions, or for assistance in developing your solution from the Visio Consulting Group, visit the Visio Web site at http://www.Visio.com or contact Visio Customer Service at 1-800-24-VISIO. Introduction ============ ActiveX technology is a relatively new and rapidly growing way to create solutions. In Visio 5.0, the Visio ActiveX control is preliminary and is intended for experienced solution providers who want a head start in creating solutions using ActiveX. We hope you will give it a try, and we encourage you to contact us with questions, comments, and suggestions so we can continue to improve this feature. We recommend you use the Visio ActiveX control in solutions created with Visual Basic 4.0 or higher or with C++ (native C++ or MFC). Using the Visio ActiveX control in control containers such as Microsoft Word 97 or Microsoft Excel 97 is not guaranteed. Licensing the Visio ActiveX Control =================================== Visio does not provide a separate license for using Visio as an ActiveX control. This means that Visio 5.0 must be installed on a user's system in order to run a solution that contains a Visio ActiveX control. Visio Corporation does offer licensing of the Visio product, so if you create Visio solutions with widespread usage you can license Visio. For more information, contact Visio Customer Service. Registering the Visio ActiveX Control ===================================== Before you can insert the Visio ActiveX control into a solution, you must register the Visio ActiveX object in the system registry. To register the Visio ActiveX control on your system, run regsvr32.exe from the folder that contains the Visio program files. If you accepted the defaults during installation, this folder is C:\Program Files\Visio. For example: REGSVR32 Vislib32.dll To remove the Visio ActiveX control from the registry, run regsvr32.exe using the /UNREGISTER flag. For example: REGSVR32 /UNREGISTER Vislib32.dll InProc Activation of the Visio ActiveX Control ============================================== When a Visio ActiveX control is inserted into a controlling application (also called the ActiveX document container) Visio is loaded in the same process space as the container. This is known as "InProc activation" and its behavior differs significantly from that of Visio objects, which are loaded out of process when inserted into a document. InProc activation improves the performance of your solution, especially during load time, because Visio is running in the same address space as the container. You will also notice that Visio.exe does not execute when a Visio ActiveX control is activated. Visio ActiveX Ambient Properties ================================ When a Visio ActiveX control is activated in an ActiveX container, the control queries the container for its ambient properties. These define the "ambient" environment provided by the container, allowing it to determine the behavior of the Visio ActiveX control with little or no programming, simply by setting the values of its ambient properties. A container can set ambient properties to change the background color of the Visio ActiveX control, enable resizing, display the control with a border, or determine whether the control is in run mode or design mode. In Visio 5.0, the Visio ActiveX control supports the following ambient properties: BackGroundColor (DISP_AMBIENT_BACKCOLOR) ---------------------------------------- Determines the background color to use when drawing a Visio page. Set BackGroundColor to the same color as the background of the ActiveX container to create a transparent effect for the Visio ActiveX control. ShowGrabHandles (DISP_AMBIENT_SHOWGRABHANDLES) ---------------------------------------------- Determines whether the Visio ActiveX control displays selection handles, which allow the user to move and size the control. This property can be used to either show the handles as you typically would in design mode, or hide them in run mode. Set ShowGrabHandles to TRUE to display selection handles on the control. Set ShowGrabHandles to FALSE to hide selection handles, which prevents the user from moving or sizing the control. ShowHatching (DISP_AMBIENT_SHOWHATCHING) ----------------------------------------- Determines whether the Visio ActiveX control displays a hatched border when the user activates the control. Set ShowHatching to TRUE to display the hatched border. Set ShowHatching to FALSE to hide the border. UserMode (DISP_AMBIENT_USERMODE) --------------------------------- Indicates whether the Visio ActiveX control is activated in run mode or design mode. If UserMode is TRUE, the Visio ActiveX control is activated in run mode, which means it fires events. If UserMode is FALSE, the Visio ActiveX control is activated in design mode, which means it does not fire events. Programming the Visio ActiveX Control ===================================== You use the same Automation techniques described in Developing Visio Solutions to program a Visio ActiveX control, with these enhancements: * The Visio object model has a new object, the Control object, which represents a drawing page in a Visio ActiveX control. The Control object has the same properties, methods, and events as a Page object, and can be used in the same way. For details, see the Page object and individual properties, methods, and events in Progref.hlp. * The Window object supports zooming and scrolling in the drawing window of a Visio ActiveX control. In Visio 4.5 and earlier, zooming and scrolling in embedded Visio objects was handled by the container, and it was not possible to zoom or scroll in the embedded Visio object independently. Use Window.Zoom to control magnification of the window (zoom in and out). Use Window.ShowScrollBars to show or hide scroll bars so the user can scroll the window. For details about Window.Zoom, see Progref.hlp. ShowScrollBars is described later in this Readme file. When you insert a Visio ActiveX object in your solution, you automatically get a reference (interface) to a Control object that represents the drawing page in that control. A Control object typically represents a foreground page, but it can represent a background page. A Visio ActiveX control typically contains a single drawing page, but it can contain multiple pages. You can access pages in such a control in the same way as in an instance of Visio, such as using the ActivePage property of the control's Application object to retrieve the active page. To get a Window object on that drawing page, get the Application property of the Control object, then get the ActiveWindow property of that Application object. For more information about working with Page and Window objects, see Developing Visio Solutions. ShowScrollBars Property ======================= Applies to: Window Summary: Determines whether Visio shows scroll bars in the window. Version: VISIO 5.0 Syntax: intRet = object.ShowScrollBars object. ShowScrollBars = intExpression Element Description intRet 0 if scrollbar display is off; -1 if scrollbar display is on object The Window object that has or gets the setting intExpression visScrollBarNeither = 0, to turn off both scroll bars. visScrollBarHoriz = 1, to display the horizontal scroll bar. visScrollBarVert = 4, to display the vertical scroll bar. visScrollBarBoth = 5, to display both scroll bars. Remarks: Currently there is no analogous option in the Visio menus for toggling the scroll bars. Inserting the Visio ActiveX Control in a Solution ================================================= Using a Visio ActiveX Control in Microsoft Visual Basic 5 --------------------------------------------------------- 1. Activate Visual Basic (VB) and create a project. 2. Choose the Project.Components menu command. 3. Scroll down, then check the Visio 5.0 Type Library item in the Components list box. You should now see the Visio icon in the VB Toolbox. 4. Select the Visio icon in the Toolbox. 5. Drag a rectangle region where you want to place the Visio ActiveX control in your VB form. This adds a Visio ActiveX control by the name of "Control1" to your VB form. 6. Select either the Run toolbar button or Run menu item to start your VB form. 7. Double-click the Visio ActiveX object to activate the Visio control. The Visio ActiveX control is now active and ready to be driven programmatically. The following code shows how you would turn on scroll bars for the control. Dim appVisio As VisioCtl.Application ' Visio's instance Dim winVisio As VisioCtl.Window ' Visio's drawing window ' Retrieve the current instance of Visio Set appVisio = Control1.Application Set winVisio = appVisio.ActiveWindow winVisio.ShowScrollBars = visScrollBarBoth Form1.Refresh Using a Visio ActiveX Control in Microsoft Visual Basic 4 --------------------------------------------------------- 1. Activate Visual Basic (VB) and create a project. 2. Choose the Tools.Custom Controls menu command. 3. Scroll down, then check the Visio 5.0 Type Library item in Components list box. You should now see the Visio icon in the VB Toolbox. 4. Select the Visio icon in the Toolbox. 5. Drag a rectangle region where you want to place the Visio ActiveX control in your VB form. This adds a Visio ActiveX control by the name of "Control1" to your VB form. 6. Select either the Run toolbar button or Run menu item to start your VB form. 7. Double-click the Visio ActiveX object to activate the Visio control. The Visio ActiveX control is now active and ready to be driven programmatically. The following code shows how you would turn on scroll bars for the control. Dim appVisio As VisioCtl.Application ' Visio's instance Dim winVisio As VisioCtl.Window ' Visio's drawing window ' Retrieve the current instance of Visio Set appVisio = Control1.Application Set winVisio = appVisio.ActiveWindow winVisio.ShowScrollBars = visScrollBarBoth Form1.Refresh Known Limitations of the Visio ActiveX Control ============================================== In Visio 5.0, you cannot insert one Visio ActiveX control into another. This is a side effect of trying to InProc-activate Vislib32.dll inside itself, which currently does not work reliably. Until this is tested further, the Visio ActiveX control has been removed from the list of controls that can be inserted into Visio. Only one Visio ActiveX control at a time can be visible and active in an ActiveX container. Again, this is a side effect of loading Vislib32.dll InProc. If your solution requires multiple Visio windows to be visible in a container application at the same time, base your solution on Visio embedded objects rather than Visio ActiveX controls. Supporting multiple active Visio ActiveX controls is planned for a future release. Visual Basic for Applications (VBA) is not supported when Visio is activated as an ActiveX control. This should have little or no effect when you are developing your solutions, because you typically use the ActiveX container to drive the Visio ActiveX control and don't need Visio's VBA. However, you cannot insert other ActiveX controls in the Visio ActiveX control, because Visio uses VBA extensively when controls are inserted in a Visio drawing. At this time Visio 5.0 does not support Property Pages, and does not provide a user interface (UI) to edit the properties of the ActiveX control. To change the properties of the control, you need to use Automation to change properties programmatically. Property Page support is planned for a future release.